
		           DoorsOS II 0.92
                          by the Doors Team
                       for TI 89 and TI92 Plus

                         Copyright  (C) 1998-1999
                            Xavier VASSOR
                          Cedric COUFFIGNAL

e-mail: 	xvassor@mail.dotcom.fr
web site: 	http://start.at/doors

                        All rights reserved.

----------------------------------------------------------------------
TABLE OF CONTENTS
----------------------------------------------------------------------

I)   Introduction
II)  Installing DoorsOS
III) Installing the explorer 'Doors Explorer'
IV)  Programming for DoorsOS
V)   Planned Features
VI)  How to contact us
VII) History

----------------------------------------------------------------------
I) Introduction
----------------------------------------------------------------------

        DoorsOS is a kernel which will allow the execution of assembly programs on your TI 89 or TI 92 Plus. In fact it actually extends the built-in assembly support.


It mainly features:
        - Library support
	- ROM Calls relocation
        - BSS support
        - Anti Crash protection!  What's more, you can press STO+ON at any time to exit programs.
        - Runs on both, TI 89 and 92 Plus
	- much more, of course :)

	Programmers may use the following distributed libraries:
        - userlib	-> common & password functions
        - graphlib	-> graphical functions
        - filelib	-> file operation functions
	- ziplib 	-> Compression / Extraction  (Made By Marc Teyssier)
	- hufflib	-> Extraction (added for anterior compatibility, use preferably ziplib)
	- hexlib	-> Display Hexadecimal numbers

DoorsOS is a freeware. The distribution of DoorsOS is encouraged, as long as all the files are kept together, and unmodified from the form in which they were originally released.

----------------------------------------------------------------------
II) Installing and using DoorsOS
----------------------------------------------------------------------

Requirements
------------

To install Doors OS you need:
        - A Graph-Link (TM) cable, or any working cable and the appropriate software (the GraphLink software (you can download it at http://www.ti.com/calc/))
        - A TI 89 or a TI 92 Plus :)
	- DoorsOS will work on all known ROM versions, including the recent 2.0x versions !
	However it has not been tested on Hardware Version 2.00 calculators. Please report what happens on these calcs to xvassor@mail.dotcom.fr.
	If DoorsOS doesn't work correctly on your ROM version, please tell us what ROM version you are using. Thanks

Installation
------------

        First, unzip all files contained in DoorsOS.zip into the folder of your choice.

        Use your link software to transfer the program, 'doorsos.89z' or 'doorsos.9xz' to your calculator.

        Run doorsos from your calculator (type 'doorsos()' at the home screen and press Enter). This will install the DoorsOS kernel on the calculator.  You can delete the 'doorsos' file from your calculator after that.

        Now you may run any assembly program: Just type the name at the home screen like you would do for a basic program.  Libraries can be in any folder, but they can be stored in RAM ONLY. Archived libraries aren't recognised by DoorsOS.

	If you press Shift-ON at any time, it will run the program named 'doors', which can be in any folder. It can't be archived

NOTE: On ROMs 2.0x, TI restricted ASM program size to 8kb ! To run programs larger than 8kb, you have to use the run() program. For example
	run("main\doors")

	You can exit all assembly programs at any time, pressing STO+ON

NOTE: Use this program at you own risk. We can't be held responsible
for any damage done to your calculator. 

If your TI89 crashes, press 2nd - Right - Left - ON to reset it.
If this doesn't work remove the 4 batteries + the Lithium battery

If your TI92+ crashes, press 2nd - Lock - ON to reset it.
If this doesn't work remove the 4 batteries + the Lithium battery

----------------------------------------------------------------------
III) Installing the Explorer 'Doors'
----------------------------------------------------------------------

After having installed Doors OS:
Be sure to transfer the following files to your calculator:

	doors		| The explorer
	filelib		| File management library
	graphlib	| Gfx functions
	userlib		| Password and common functions
		by the Doors Team

	ziplib		| Compression library by Marc Teyssier

You can run the Doors Explorer pressing 'Shift-On'.
Of course it can also be executed from the Home screen.
Please read Doors-Explorer.txt for more info about it

----------------------------------------------------------------------
IV) Programming for Doors
----------------------------------------------------------------------

First of all, there are 2 different types of programs: programs and libraries. The only differences between them is that programs have:
	- An optional comment
	- A main entry point

        Those are the only differences, so programs AND libraries can export functions, BSS blocks, import functions from others programs and libraries, and have an exit point.

How to compile a program or a library
-------------------------------------

Suppose that you unzipped Doors in the folder C:\Doors.  The first thing to do is to add these lines in your autoexec.bat:

SET DOORSOS=C:\DOORS
SET PATH=%PATH%;%DOORSOS%\BIN

Now you can compile a program or library from the Dos command line:

C:\DOORS>Doors <prog>

With "prog" being the name of the .asm file without its extension.

General
-------
        Every program should include the header file "doorsos.h" at the beginning.  To define which calculator the program is designed to run under, the programmer adds the following lines:
        
	xdef    _ti89           to compile a .89z file
        xdef    _ti92plus       to compile a .9xz file

Both lines can be written so that the file is compiled for both calcs.  To learn programming, you should read all documents in the doc directory.


The Exit Point
--------------

The Anti Crash protection is activated when an error such as an Address error, Illegal instruction, etc.. occurs. It allows you to keep your memory intact. But the program can maybe have some things to do before exiting. Our kernel calls the exit point of each program when a crash occurs, so that the program do what it wants before ending.
Note that the exit point is optional.

The exit point is defined with;
        xdef    _exit
        (...)
_exit:

At _exit: you will write your exit code. Here is a small example: It will free memory supposed to be used by the program

        xdef    _exit
        (...)
_exit:
        tst.w   handle  ;tests if handle was allocated when the crash occurred
        beq     \notalloc
        move.w  handle,-(a7)
        jsr     doorsos::HeapFree       ;Frees the memory
        addq.l  #2,a7
\notalloc
        rts             ;IMPORTANT ! This code must end with an rts

        (...)
handle  dc.w    0       ;variable supposed to contain a handle number

NOTE: It is important that this code is totally bug-free!  If it crashes, there
would be a recursive and endless call to the Anti Crash protection and
the user would have to reset his/her calculator.

How to Export functions
-----------------------
At the beginning of your program or library, you can export functions with a 'xdef    prog@XXXX' line, XXXX being an hexadecimal number. It indicates the index of the exported function.

But programs and libraries should have their include file whenever they export functions. For example, for a library called "graph", suppose that graph@0000 clears the screen. Then in "graph.h" there should be:

graph::clearscr equ     graph@0000

Then if a program or a library wants to use this function, it will just have to include "graph.h" at the beginning, and when it wants to clear
the screen, it writes:

        jsr     graph::clearscr


Program example:
----------------
Let's call it 'test'.

        include "doorsos.h"     ;aliases for ROM functions and RAM addresses
        include "lib.h"         ;allows the use of functions exported from 'lib'
        xdef    _ti89
        xdef    _ti92plus       ;compiles for both calcs
        xdef    _main   ;tells that there is an entry point, so we know this is a program
        xdef    _comment ;do this only if you want a comment 
        xdef    test@0000       ;first exported function
        ...
_main:                  ;label of the beginning code of you program
        ...
test@0000:              ;first exported function
        ...
        rts             ;return from function
        ...
        jsr     lib::function   ;calls a function in 'lib'
        rts     ; return from program
        ...
_comment        dc.b    "Program version 2.0",0

        BSS     ;tells there is a BSS block
;define here all vars you want to be in the BSS block.
;they are not initialized
buffer  ds.b    50
        ...

        end     ;tells the assembler that the file is finished.

Note: You don't always need to define comment, or to use a BSS block.

Library example:
----------------

Let's call this library 'lib'.

        include "doorsos.h"     ;aliases for ROM functions and RAM addresses
        xdef    _ti89
        xdef    _ti92plus       ;compiles for both calcs
        xdef    _library        ;tells that this is a library. 
        xdef    lib@0000
        xdef    lib@0001
        ...
        xdef    lib@XXXX

lib@0000:
        ...
        rts     ;exits

lib@0001:
        ...
        rts     ;exits

        ...

        end     ;the file is finished.


----------------------------------------------------------------------
                        V) Planned Features
----------------------------------------------------------------------

- Compatibility with Hardware Version 2.00 calculators.
- Just implement TI's infos.. when they'll be released..

----------------------------------------------------------------------
                        VI) How to contact us
----------------------------------------------------------------------

You can e-mail us at: <xvassor@mail.dotcom.fr>

If you have a question about programming, you would be better off mailing
to the Assembly-89 mailing list <assembly-89@lists.ticalc.org>
or the Assembly-92 mailing list <assembly-92@lists.ticalc.org>

Please report any and all bugs you find using DoorsOS, so that we may correct them quickly !
However, please try to give a precise description of what you did and what happened. Thanks.
Also please don't be frustrated if I don't answer your mail. I get a lot of e-mail and I don't have the time anymore to answer them all. Thank you for your understanding.

----------------------------------------------------------------------
                        VII) History
----------------------------------------------------------------------

12/26/2000:
	- DoorsOS II 0.92 released !
	- Minor bug fix in the installer.
	- Major bug fix : now works on all AMS 2.03 ! It may also now work on HW2 calcs, although I couldn't test it.

12/24/1999:
	- DoorsOS II 0.9 released !

 ---------
|FOR USERS|
 ---------
	- Works on all known ROM versions !
	However Hardware Version 2.00 calculators may still have problems
	If DoorsOS doesn't work with your ROM version, please tell us which version it is ! Thanx
	- Now doors can be in any folder when you attempt to run it with Shift-ON
	- Libraries can't be archived anymore because it was really unsafe.
	- When you attempt to run an archived program, it will be temporarily copied to RAM but not unarchived and archived back. In this case, changes in the program (such as High Scores) won't be saved.
	- For ROM 2.0x, you can execute ASM programs larger than 8kb using the run() program. (Thanx to b.lesteven).
	- Had to remove the 92+ installation picture because of this stupid 8kb size restriction...
	- ESC-ON has been replaced (temporarily ?) by STO-ON. Press now STO-ON to quit all ASM progs.
	- Thanx to Marc Teyssier for his help

 ---------------
|FOR PROGRAMMERS|
 ---------------

	- Due to the need for compatibility with the new ROM versions, a few things have changed.
   YOU MUST PORT YOUR PROGRAMS TO MAKE THEM WORK WITH ALL ROM VERSIONS (see below).

	- A new RAM CALL allows you to know which ROM version your program is running on. Use it this way:
	move.w	#ROM_VERSION,d0

	|------------------------------------------------|
	| ROM_VERSION values | Corresponding ROM Version |
	|------------------------------------------------|
	| $1100		     |	92+ 1.00		 |
	| $0100		     |	89  1.00		 |
	| $1101		     |	92+ 1.01		 |
	| $0105		     |	89  1.05		 |
	| $1105		     |	92+ 1.05		 |
	| $0201		     |	89  2.01		 |
	| $1201		     |	92+ 2.01		 |
	| $0203		     |	89  2.03		 |
	| $1203		     |	92+ 2.03		 |
	| $0000		     |	UNKNOWN 89		 |
	| $1000		     |	UNKNOWN 92+		 |
	|------------------------------------------------|


	- The doorsos::kb_vars and doorsos::Heap variables are now RAM CALLS, ie. managed by the kernel. 

	- Since the handle of the folder list and of the 'main' folder changed in the new ROM, they are now RAM CALLS too. To use them, do the following:
	move.w	#doorsos::FolderListHandle,d0 ; Don't forget the '#' before !
and
	move.w	#doorsos::MainHandle,d0

		 ------------------------------
		| PLEASE PORT YOUR PROGRAMS !! |
		 ------------------------------

Please take the time to port your programs ! There is very few to do, and when done your program will be compatible with all ROM versions. Here is how to make your program compatible

	- Don't use any direct RAM address.
	- If you use doorsos::Heap, doorsos::kb_vars, you have to recompile using the new DoorsOS.h from this package.

	- Please replace any use of $8 and $9 as handle of (respectively) the folder list and the main folder:
		move.w	#$8,d0	; d0 = handle of the folder list
		move.w	#$9,d1	; d1 = handle of the main folder

	will be replaced by:

		move.w	#doorsos::FolderListHandle,d0	; same as before, but it will
		move.w	#doorsos::MainHandle,d0		; work on ALL ROM versions

	- That's all you have to do ! :-)

07/16/1999:
	- Doors OS Final Version beta2 released !
	- Now distributed under 2 forms: user and developer versions.
	- To those who haven't had the beta version, have a look at the history below.
	- The Shift-ON hook is now completely stable, but (as a side effect) it can only run Doors if it is in the current folder. This might be improved later.
	- Ziplib now supports archived files (good job Marc :) )
	- Added a 'Ziper' program on PC, you can compress files on your computer and then send them to the TI !
	- Thanx to Johan Eilert, I'm on the way of making Doors OS really compatible w/ future ROM versions. However, this could not be finished yet :(
        - Thanks to Chris Ivarson for converting the docs (you are reading) to HTML

For the Programmers:
	- Now there is a true linker !
		- can link multiple .o files
		- supports the _nostub directive
		- is much better in general :)
	- you now can use cross references with libraries, ie. lib1 can use lib2 AND lib 2 can use  lib1.
	- userlib::exec now supports archived AND zipped programs
	- userlib::runprog is a brand new function that will run any command line program ! (ASM, PRGM, or FUNC).

04/20/1999:
	- Doors OS Final Version beta1 released !
For the Users:
	- Total support for archived variables !
	- The Explorer is now in French !
	- Changed the installation pictures (thanks to Etan21 for them)
	- Definitely fixed the addresses of the Font Tables :) (thanks to Fred)
	- Improved a tiny bit of the Anti Crash protection
	- Fixed a bug which caused the calc to freeze sometimes when you pressed ESC-ON (thanks to Mikael Sundberg who found it)
	- Fixed the HeapAlloc bug another way, much better :)
	- Removed the program 'moremem' from the package, because using it caused the garbage collections to be buggy :-(
For the Programmers:
	- Fixed bugs in objtobin.exe (the linker), it now works much better :)
	- Modified filelib::gettype to make it work with the last release of ziplib. What's more, it now recognizes the type: 'OTHER' 
	- Added a function graphlib::getlength, and modified userlib::smallmenu a lot. Check out the .h files for more info
	- Added EQUs for ALL rom calls in DoorsOS.h, however they are not documented
	- Added macros in DoorsOS.h to define pseudo instructions: push, pop, pushm, popm, inc, dec
	- Your program can now return values to the TIOS. See RAM&ROM.txt for more info.
	- You may note that this version is internally called 1.01 even if it doesn't much matter..

02/13/1999:
	- Doors OS 1.0 released !
	- Fixed a small bug
	- Added a picture when installation is successful (thanks to Pierre Henninger for his pics)
	- Added a 7 grayscale example program from Miles Raymond (thanks to him)
	- userlib::exec can now run *only* programs compiled with the new format. This prevents the TI from crashing sometimes.
	- Fixed a TI bug. The HeapAlloc function could crash sometimes, this is fixed by DoorsOS :)
	- Fixed the addresses of the Font Tables
	- Fixed a bug with graphlib::gray7
	- Fixed all bugs ?? I really hope so.. :) That is why this version is no more called 'beta'. It should be the final release.

12/29/1998:
	- Doors OS 0.96 beta released !
	- Fixed a big bug in the previous version. This one is now stable :-)  There is still maybe ONE bug left, that make the Explorer do an Address Error. Anyway I can't have it again.
If the explorer has an Address Error bug, please mail me !
	- Now automatically recovers any memory left unfreed by a program ! (Thanks to David Kuhling)
	- Still improved a little the Shift-ON Combo with the help of David Ellsworth.
	- Corrected the address of doorsos::ST_flags in doorsos.h

12/26/1998:
	- Doors OS 0.95 beta released !
	- Improved the Anti Crash protection ! It now recovers better from a crash.
	- Improved the Shift-ON Combo ! It is cleaner !
	- added Font table addresses in DoorsOS.h
	- added Handles.txt in the doc
	- added function getfreearchive in userlib
	- improved filelib::hdltoindex, it will now recognize when you
look for a folder
	- improved filelib::search, it could only return the first file
it found, now you can get the file found after <d1> searches
	- This version should be the last beta version since it is
supposed to be really stable now.


12/06/1998:
	- Doors OS 0.91 beta released !
	- fixed a bug in the Shift-ON combo

11/28/1998:
        - Doors OS 0.9 beta released !
	- Ported the explorer to TI 89 ! Read Doors-Explorer.txt
        - Libraries can be in any folder now !
        - Added the "Shift-ON" combo which launches the program named "doors" at any time.
          For now, it can't display anything if there is an error
        - now automatically replaces the old kernel
        - added an 'uninstall' program
        - added functions: 
        filelib::search
	filelib::createfile
	filelib::resizefile
	filelib::readfile
	filelib::writefile
	graphlib::erase_rect
	graphlib::frame_rect
	graphlib::line

        - enlarged the smallbox in graphlib on the 89.
        - added Macros in doorsos.h : WriteStr, WriteStrA, SetFont, 
	GetKeyStat.
        - fixed bugs in: doorsos::FolderListHandle,doorsos::MainHandle,
                        doorsos::DefTempHandle, Anti Crash protection,
                        userlib::getfreeRAM

10/25/1998:
        - Doors OS 0.85 beta released !
        - Added password functions, InputStr and smallmenu in userlib
        - Included the filelib library: file operation functions
        - Ported hexlib and hufflib to Doors OS.
        - Ported our TI92 explorer to Doors OS! (for TI92+ only)
        - Added doorsos::ST_flags and KEY_SHIFT aliases in doorsos.h
        - fixed bugs in: 
		graphlib::scrtomem & graphlib::memtoscr 
		userlib::FindSymEntry
		Anti Crash protection
		KEY_RIGHT,KEY_LEFT,KEY_UP,KEY_DOWN aliases
		1st EXTRA RAM TABLE entry (thanks to Rusty Wagner)


10/18/1998:
        - Doors OS 0.8 beta released !
        - A new file format has been chosen and implemented.
        - Anti Crash protection implemented !
        - Released the graphlib library and added some functions in userlib.
        - Some bugs were fixed in the compiler.
        - Many more docs even if they aren't complete yet.
        - More sample progs

9/20/1998:
        - Doors OS 0.7 beta released !

